doc: Update instructions on using native-completions #15480
Conversation
`~/.local/share/bash-completion/completions/cargo` is more sensible, and [recommended by rustup](https://github.com/rust-lang/rustup/blob/e4f3ad6f893e56ca10f0a329c401a5eafab69607/src/cli/help.rs#L275).
rustbot
added
A-documenting-cargo-itself
|
I'm not too familiar with how the different completion locations are loaded. So you are saying the following source <(CARGO_COMPLETE=bash cargo +nightly)Have you tested this? Its important to note that we are not telling people to $ CARGO_COMPLETE=bash cargo +nightly > ~/.local/share/bash-completion/completions/cargoAnd speaking of rustup, why does it have you append to the file? That seems bad if the person forgets and does it again |
|
Hmm, looking into that documentation in rustup, it is to conform to https://github.com/scop/bash-completion/blob/main/README.md My question would then be how often is that installed and used? |
| @@ -1816,10 +1816,10 @@ When in doubt, you can discuss this in [#14520](https://github.com/rust-lang/car | |||
|
|
|||
| ### How to use native-completions feature: | |||
| - bash: | |||
| Add `source <(CARGO_COMPLETE=bash cargo +nightly)` to your .bashrc. | |||
| Add `source <(CARGO_COMPLETE=bash cargo +nightly)` to `~/.local/share/bash-completion/completions/cargo`. | |||
There was a problem hiding this comment.
Or make it XDG_DATA_HOME, which
- bash-completion recommends: https://github.com/scop/bash-completion/blob/89aa18b15462f117c20cde5f71e109c2f616bb62/README.md?plain=1#L153-L161
- We already did that for fish:
cargo/src/doc/src/reference/unstable.md
Lines 1824 to 1828 in 8b5c351
There was a problem hiding this comment.
Or make it
XDG_DATA_HOME
Maybe some fallback method should be mentioned, in case the env var doesn't exist?
There was a problem hiding this comment.
According to the code, the .local/share directory will be used as a fallback for XDG_DATA_HOME.
There was a problem hiding this comment.
The suggested fallback of XDG_DATA_HOME is exactly $HOME/.local/share. I think saying XDG_DATA_HOME is good enough, alike elvish and fish.
https://specifications.freedesktop.org/basedir-spec/latest/#variables
There was a problem hiding this comment.
iirc XDG correctly, when you are reading or writing to a location, you can assume that if XDG_DATA_HOME is not present, you can assume that location. The key is that XDG_DATA_HOME may not be present.
We can then either
- Use
XDG_DATA_HOME - Use
${XDG_DATA_HOME:-$HOME/.local/share}(fallback in the copy/paste) - Document the fallback if
XDG_DATA_HOMEis unset - Assume what
XDG_DATA_HOMEresolves to
I think that this, in part, depends on
- How much noise (and in what form) we are ok with the instructions
- How likely
XDG_DATA_HOMEis specified and how astute are the readers without it set for them to recognize the problem and resolve it
There was a problem hiding this comment.
- Use XDG_DATA_HOME
- Document the fallback if XDG_DATA_HOME is unset
Personally prefer to these two. If we chose the latter, then we also want to update elvish and fish's docs.
There was a problem hiding this comment.
At least on my system, XDG_DATA_HOME is not set. If thats representative, then these solutions would basically be setting the user up for failure and they wouldn't notice until files were written into the current directory.
Let's also put this in context: this is documentation for testing an unstable feature, not the regular end-user instructions for this feature.
I've tested it on Ubuntu 24.04.2 LTS, with |
Regarding that they used |
That is not very extensive when we expect this to be used on many different types of systems. In particular, I'm wondering about how often |
~/.local/share/bash-completion/completions/cargois more sensible, and recommended by rustup.